home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / Extras / opussdk / docs / dos.doc < prev    next >
Text File  |  1996-09-05  |  14KB  |  408 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/DateFromStrings
  4. dopus5.library/DeviceFromHandler
  5. dopus5.library/DeviceFromLock
  6. dopus5.library/DevNameFromLock
  7. dopus5.library/FreeDosPathList
  8. dopus5.library/GetDosPathList
  9. dopus5.library/GetFileVersion
  10. dopus5.library/LaunchCLI
  11. dopus5.library/LaunchWB
  12. dopus5.library/ParseDateStrings
  13. dopus5.library/SearchFile
  14. dopus5.library/SetEnv
  15. dopus5.library/DateFromStrings                 dopus5.library/DateFromStrings
  16.  
  17.     NAME
  18.         DateFromStrings - convert date and time strings to a datestamp
  19.  
  20.     SYNOPSIS
  21.         DateFromStrings(date, time, ds)
  22.                          A0    A1   A2
  23.  
  24.         BOOL DateFromStrings(char *, char *, struct DateStamp *);
  25.  
  26.     FUNCTION
  27.         This routine takes a date string and a time string and converts them
  28.         to a DOS DateStamp. The DOS StrToDate() routine is used to perform
  29.         this conversion, so it is sensitive to the current locale. If the
  30.         time string contains an 'a' or a 'p' to signify am or pm, it
  31.         is automatically converted to 24 hour time for the DOS call.
  32.  
  33.     INPUTS
  34.         date - date string to convert
  35.         time - time string to convert
  36.         ds - DateStamp to store result
  37.  
  38.     RESULT
  39.         Returns TRUE if successful.
  40.  
  41.     SEE ALSO
  42.         ParseDateStrings(), dos.library/StrToDate()
  43.  
  44. dopus5.library/DeviceFromHandler             dopus5.library/DeviceFromHandler
  45.  
  46.     NAME
  47.         DeviceFromHandler - returns device name from handler
  48.  
  49.     SYNOPSIS
  50.         DeviceFromHandler(handler, buffer)
  51.                             A0       A1
  52.  
  53.         struct DosList *DeviceFromHandler(struct MsgPort *, char *);
  54.  
  55.     FUNCTION
  56.         This function takes a pointer to a filesystem's handler
  57.         (message port) and returns the associated device name.
  58.  
  59.     INPUTS
  60.         handler - pointer to handler message port
  61.         buffer - buffer to store device name (must be >=34 bytes)
  62.  
  63.     RESULT
  64.         If the port supplied is a valid filesystem handler, the
  65.         name of the device is stored in the supplied buffer, and
  66.         a pointer to the DosList entry for that device is returned.
  67.  
  68.     SEE ALSO
  69.         DeviceFromLock(), DevNameFromLock()
  70.  
  71. dopus5.library/DeviceFromLock                   dopus5.library/DeviceFromLock
  72.     NAME
  73.         DeviceFromLock - returns device name from a filelock
  74.  
  75.     SYNOPSIS
  76.         DeviceFromLock(lock, buffer)
  77.                         A0     A1
  78.  
  79.         struct DosList *DeviceFromLock(BPTR, char *);
  80.  
  81.     FUNCTION
  82.         This function takes a filelock and returns the name of the
  83.         device that lock resides on.
  84.  
  85.     INPUTS
  86.         lock - pointer to lock
  87.         buffer - buffer to store device name (must be >=34 bytes)
  88.  
  89.     RESULT
  90.         The name of the device is stored in the supplied buffer, and
  91.         a pointer to the DosList entry for that device is returned.
  92.  
  93.     SEE ALSO
  94.         DeviceFromHandler(), DevNameFromLock()
  95.  
  96. dopus5.library/DevNameFromLock                 dopus5.library/DevNameFromLock
  97.  
  98.     NAME
  99.         DevNameFromLock - return the full pathname of a file
  100.  
  101.     SYNOPSIS
  102.         DevNameFromLock(lock, buffer, size)
  103.                          D1     D2     D3
  104.  
  105.         BOOL DevNameFromLock(BPTR, char *, long);
  106.  
  107.     FUNCTION
  108.         Returns a fully qualified path for the lock. The only difference
  109.         between this function and the equivalent DOS library routine is
  110.         that the device name of the disk is returned, rather than the
  111.         volume name.
  112.  
  113.         For example, if the NameFromLock() routine returned :
  114.  
  115.             Workbench:S/startup-sequence
  116.  
  117.         The DevNameFromLock() routine would return :
  118.  
  119.             DH0:S/startup-sequence
  120.  
  121.     INPUTS
  122.         lock - filelock to obtain the path for
  123.         buffer - buffer to store path
  124.         size - size of buffer
  125.  
  126.     RESULT
  127.         This function returns TRUE if it succeeds.
  128.  
  129.     SEE ALSO
  130.         DeviceFromLock(), dos.library/NameFromLock()
  131.  
  132. dopus5.library/FreeDosPathList                 dopus5.library/FreeDosPathList
  133.  
  134.     NAME
  135.         FreeDosPathList - free a DOS path list
  136.  
  137.     SYNOPSIS
  138.         FreeDosPathList(list)
  139.                          A0
  140.  
  141.         void FreeDosPathList(BPTR);
  142.  
  143.     FUNCTION
  144.         This function frees a standard DOS path list, by unlocking each
  145.         lock and FreeVec()ing each entry.
  146.  
  147.     INPUTS
  148.         list - pointer to head of list
  149.  
  150.     RESULT
  151.         The list is freed.
  152.  
  153.     SEE ALSO
  154.         GetDosPathList()
  155.  
  156. dopus5.library/GetDosPathList                   dopus5.library/GetDosPathList
  157.  
  158.     NAME
  159.         GetDosPathList - get a copy of a DOS path list
  160.  
  161.     SYNOPSIS
  162.         GetDosPathList(list)
  163.                         A0
  164.  
  165.         BPTR GetDosPathList(BPTR);
  166.  
  167.     FUNCTION
  168.         This routine has two uses. The first is to copy an existing DOS
  169.         path list that you supply. The second is to attempt to find and copy
  170.         the system path list.
  171.  
  172.     INPUTS
  173.         list - path list to copy or NULL
  174.  
  175.     RESULT
  176.         If you supply a path list, it will be copied and the address of the
  177.         first entry of the new list will be returned.
  178.  
  179.         If you pass NULL, this routine attempts to find a system path list to
  180.         copy. The Amiga has no definitive path list, so the only way to
  181.         obtain one is to copy it from another process. This routine looks for
  182.         the following processes (in order) : Workbench, Initial CLI, Shell
  183.         Process, New_WShell and Background CLI. If one of these processes is
  184.         found and it has a valid path list, that list is copied and returned
  185.         to you.
  186.  
  187.     NOTES
  188.         If Workbench is not running, Opus creates a dummy task called
  189.         'Workbench', purely to provide a path list for programs that use this
  190.         method.
  191.  
  192.     SEE ALSO
  193.         FreeDosPathList()
  194.  
  195. dopus5.library/GetFileVersion                   dopus5.library/GetFileVersion
  196.  
  197.     NAME
  198.         GetFileVersion - get a file's version information
  199.  
  200.     SYNOPSIS
  201.         GetFileVersion(name, verptr, revptr, date, progress)
  202.                         A0     D0      D1     A1      A2
  203.  
  204.         BOOL GetFileVersion(char *, short *, short *,
  205.                             struct DateStamp *, APTR);
  206.  
  207.     FUNCTION
  208.         This routine examines the given file and returns the file's version
  209.         number and revision, and creation date if available. It looks primarily
  210.         for a $VER string, but also understands the format of libraries,
  211.         devices, etc, and can extract the version from the Romtag structure in
  212.         the file. You can also supply a Progress handle if you want to use a
  213.         progress indicator while looking for the version information.
  214.  
  215.     INPUTS
  216.         name - full pathname of file to examine
  217.         verptr - pointer to short to receive the version number
  218.         revptr - pointer to short to receive the revision number
  219.         date - pointer to DateStamp structure (NULL if no date needed)
  220.         progress - pointer to progress indicator (or NULL)
  221.  
  222.     RESULT
  223.         Returns TRUE if a valid version number was found (this does not
  224.         necessarily mean that a date was found too).
  225.  
  226. dopus5.library/LaunchCLI                             dopus5.library/LaunchCLI
  227.  
  228.     NAME
  229.         LaunchCLI - launch a program as a CLI process
  230.  
  231.     SYNOPSIS
  232.         LaunchCLI(name, screen, curdir, input, output, wait)
  233.                    A0     A1      D0      D1     D2     D3
  234.  
  235.         BOOL LaunchCLI(char *, struct Screen *, BPTR, BPTR, BPTR, short);
  236.  
  237.     FUNCTION
  238.         This routine makes it easy to launch a program as a CLI process. The
  239.         launched process will have a full path list and copy of local
  240.         environment variables. You can have the process launched synchronously,
  241.         which means this function would not return until the process quit.
  242.         The stack size is fixed to 4096 bytes.
  243.  
  244.     INPUTS
  245.         name - name of the program to launch, including any arguments
  246.         screen - a screen for errors to appear on (or NULL for default)
  247.         curdir - lock for current directory, or NULL for default
  248.         input - file handle for standard input, or NULL
  249.         output - file handle for standard output, or NULL
  250.         wait - set to TRUE if you want to wait for the process to return
  251.  
  252.     RESULT
  253.         Returns TRUE if the process was launched successfully. If the
  254.         'wait' parameter was set to TRUE, will not return until the child
  255.         process does.
  256.  
  257.     NOTES
  258.         This function will search the current path list for your program
  259.         if you do not specify the full path.
  260.  
  261.     SEE ALSO
  262.         LaunchWB, dos.library/SystemTagList
  263.  
  264. dopus5.library/LaunchWB                               dopus5.library/LaunchWB
  265.  
  266.     NAME
  267.         LaunchWB - launch a program as a Workbench process
  268.  
  269.     SYNOPSIS
  270.         LaunchWB(name, screen, wait)
  271.                    A0     A1    D0
  272.  
  273.         BOOL LaunchWB(char *, struct Screen *, short);
  274.  
  275.     FUNCTION
  276.         This routine makes it easy to launch a program as a Workbench process.
  277.         Workbench processes expect to receive a startup message from the
  278.         launching process, and ordinarily the launching process must wait
  279.         until this message is replied to. Using this function relieves you
  280.         of this - you can launch the process and then forget about it.
  281.         The launched process will have a full path list and copy of local
  282.         environment variables.
  283.  
  284.     INPUTS
  285.         name - name of the program to launch, including any arguments
  286.         screen - a screen for errors to appear on (or NULL for default)
  287.         wait - set to TRUE if you want to wait for the process to return
  288.  
  289.     RESULT
  290.         Returns TRUE if the process was launched successfully. If the
  291.         'wait' parameter was set to TRUE, will not return until the child
  292.         process does. Otherwise, it will return immediately and you do not
  293.         need to wait for a reply to the startup message.
  294.  
  295.     NOTES
  296.         This function will search the current path list for your program
  297.         if you do not specify the full path.
  298.  
  299.     SEE ALSO
  300.         LaunchCLI, dos.library/SystemTagList
  301.  
  302. dopus5.library/ParseDateStrings               dopus5.library/ParseDateStrings
  303.  
  304.     NAME
  305.         ParseDateStrings - parse a date/time string into separate buffers
  306.  
  307.     SYNOPSIS
  308.         ParseDateStrings(string, date, time, rangeptr)
  309.                            A0     A1    A2      A3
  310.  
  311.         char *ParseDateStrings(char *, char *, char *, long *);
  312.  
  313.     FUNCTION
  314.         This function takes a date/time string (eg "8-12-95 10:34:18") and
  315.         splits the date and time elements into separate buffers. It also
  316.         supports the use of the '>' character to indicate ranges. For
  317.         example, "10-jan-94 > 15-jun-95" would indicate any date between
  318.         those dates.
  319.  
  320.     INPUTS
  321.         string - combined date/time string. This routine is smart enough
  322.                  to handle it if the time comes before the date, or
  323.                  vice versa, and it also deals reasonably well with
  324.                  different types of date inputs.
  325.         date - buffer to receive the date component (>=22 bytes)
  326.         time - buffer to receive the time component (>=22 bytes)
  327.         rangeptr - long pointer to receive the range code (or NULL)
  328.  
  329.     RESULT
  330.         The return from this function is a pointer to the end of the
  331.         parsed part of the input string. If the range returns RANGE_BETWEEN
  332.         (to signify a range between two dates), you will need to call
  333.         ParseDateStrings() again on the remainder of the string to get the
  334.         next date and time.
  335.  
  336.     SEE ALSO
  337.         DateFromStrings()
  338.  
  339. dopus5.library/SearchFile                           dopus5.library/SearchFile
  340.  
  341.     NAME
  342.         SearchFile - search a file or buffer for a text string
  343.  
  344.     SYNOPSIS
  345.         SearchFile(file, text, flags, buffer, bufsize)
  346.                     A0    A1     D0     A2      D1
  347.  
  348.         long SearchFile(APTR, UBYTE *, ULONG, UBYTE *, ULONG);
  349.  
  350.     FUNCTION
  351.         This routine searches a file, either on disk or in memory, for
  352.         a specified text string. It supports hex or decimal ascii values,
  353.         and limited wildcard searching. To search for a hex string,
  354.         the supplied search string should begin with a $ and then consist
  355.         of two-character hex codes. When searching for plain text, a
  356.         decimal ascii value can be specified with a \ character (eg \127).
  357.         A literal \ is given as \\. A question mark (?) is used as a
  358.         single wildcard character in both hex and text searches.
  359.  
  360.     INPUTS
  361.         file - buffered IO file handle
  362.         text - text string to search for
  363.         flags - Combination of the following flags :
  364.  
  365.                    SEARCH_NOCASE     - not case sensitive
  366.                    SEARCH_WILDCARD   - support ? as a wildcard character
  367.                    SEARCH_ONLYWORDS  - only match whole words
  368.  
  369.         buffer - memory buffer to search if no file specified
  370.         bufsize - size of memory buffer
  371.  
  372.     RESULT
  373.         If the supplied string is found, the offset within the file/buffer
  374.         of the first instance is returned. If no match is found or an error
  375.         occurs, -1 is returned.
  376.  
  377. dopus5.library/SetEnv                                   dopus5.library/SetEnv
  378.  
  379.     NAME
  380.         SetEnv - set a global environment variable
  381.  
  382.     SYNOPSIS
  383.         SetEnv(name, string, permanent)
  384.                 A0     A1        D0
  385.  
  386.         void SetEnv(char *, char *, BOOL);
  387.  
  388.     FUNCTION
  389.         This routine sets the named environment variable to the supplied
  390.         string value, and optionally saves it permanently.
  391.  
  392.     INPUTS
  393.         name - name of the variable to set
  394.         string - text string to set the variable to (must be null-terminated)
  395.         permanent - set to TRUE if you want the variable saved
  396.  
  397.     RESULT
  398.         The environment variable will be created if it does not exist. Any
  399.         sub-directories that are needed will also be created. For example,
  400.         if you set the variable "foo/bar/baz", the directories "env:foo"
  401.         and "env:foo/bar" would be automatically created if they did not
  402.         exist. If you set the 'permanent' flag to TRUE, the variable
  403.         will also be created in the ENVARC: directory.
  404.  
  405.     SEE ALSO
  406.         dos.library/GetVar
  407.  
  408.